Getting Started¶
This notebook introduces the basics of using xarray_plotly for interactive visualization.
Basic Usage¶
Import the xpx function for full IDE code completion:
In [1]:
Copied!
import numpy as np
import pandas as pd
import xarray as xr
from xarray_plotly import config, xpx
config.notebook() # Configure Plotly for notebook rendering
import numpy as np
import pandas as pd
import xarray as xr
from xarray_plotly import config, xpx
config.notebook() # Configure Plotly for notebook rendering
Create Sample Data¶
Let's create a DataArray with multiple dimensions:
In [2]:
Copied!
# Create sample climate data
np.random.seed(42)
da = xr.DataArray(
np.random.randn(50, 3, 2).cumsum(axis=0), # Random walk
dims=["time", "city", "scenario"],
coords={
"time": pd.date_range("2020-01-01", periods=50, freq="D"),
"city": ["New York", "Los Angeles", "Chicago"],
"scenario": ["baseline", "warming"],
},
name="temperature",
attrs={"long_name": "Temperature Anomaly", "units": "°C"},
)
da.to_dataframe()
# Create sample climate data
np.random.seed(42)
da = xr.DataArray(
np.random.randn(50, 3, 2).cumsum(axis=0), # Random walk
dims=["time", "city", "scenario"],
coords={
"time": pd.date_range("2020-01-01", periods=50, freq="D"),
"city": ["New York", "Los Angeles", "Chicago"],
"scenario": ["baseline", "warming"],
},
name="temperature",
attrs={"long_name": "Temperature Anomaly", "units": "°C"},
)
da.to_dataframe()
Out[2]:
| temperature | |||
|---|---|---|---|
| time | city | scenario | |
| 2020-01-01 | New York | baseline | 0.496714 |
| warming | -0.138264 | ||
| Los Angeles | baseline | 0.647689 | |
| warming | 1.523030 | ||
| Chicago | baseline | -0.234153 | |
| ... | ... | ... | ... |
| 2020-02-19 | New York | warming | -13.111345 |
| Los Angeles | baseline | -10.375200 | |
| warming | -1.301501 | ||
| Chicago | baseline | -5.211987 | |
| warming | 17.857366 |
300 rows × 1 columns
Your First Plot¶
Create an interactive line plot with a single method call:
In [3]:
Copied!
# Dimensions auto-assign: time→x, city→color, scenario→facet_col
fig = xpx(da).line()
fig
# Dimensions auto-assign: time→x, city→color, scenario→facet_col
fig = xpx(da).line()
fig
The plot is fully interactive:
- Zoom: Click and drag to select a region
- Pan: Hold shift and drag
- Hover: See exact values at each point
- Toggle traces: Click legend items to show/hide
Dimension Assignment¶
Dimensions are assigned to plot "slots" based on their order:
| Dimension | Slot |
|---|---|
| time (1st) | x-axis |
| city (2nd) | color |
| scenario (3rd) | facet_col |
You can override this with explicit assignments:
In [4]:
Copied!
# Put scenario on color, city on facets
fig = xpx(da).line(color="scenario", facet_col="city")
fig
# Put scenario on color, city on facets
fig = xpx(da).line(color="scenario", facet_col="city")
fig
Skipping Slots¶
Use None to skip a slot entirely:
In [5]:
Copied!
# Skip color, so city goes to line_dash instead
fig = xpx(da.sel(scenario="baseline")).line(color=None)
fig
# Skip color, so city goes to line_dash instead
fig = xpx(da.sel(scenario="baseline")).line(color=None)
fig
Customization¶
All methods return a Plotly Figure that you can customize:
In [6]:
Copied!
fig = xpx(da).line()
fig.update_layout(
title="Temperature Anomaly Projections",
template="plotly_white",
legend_title_text="City",
)
fig
fig = xpx(da).line()
fig.update_layout(
title="Temperature Anomaly Projections",
template="plotly_white",
legend_title_text="City",
)
fig
You can also pass Plotly Express arguments directly:
In [7]:
Copied!
fig = xpx(da).line(
title="Temperature Trends",
color_discrete_sequence=["#E63946", "#457B9D", "#2A9D8F"],
template="simple_white",
)
fig
fig = xpx(da).line(
title="Temperature Trends",
color_discrete_sequence=["#E63946", "#457B9D", "#2A9D8F"],
template="simple_white",
)
fig
Configuration¶
Customize label extraction and other behavior with the config module:
In [8]:
Copied!
# View current options
config.get_options()
# View current options
config.get_options()
Out[8]:
{'label_use_long_name': True,
'label_use_standard_name': True,
'label_include_units': True,
'label_unit_format': '[{units}]',
'slot_orders': {'line': ('x',
'color',
'line_dash',
'symbol',
'facet_col',
'facet_row',
'animation_frame'),
'bar': ('x',
'color',
'pattern_shape',
'facet_col',
'facet_row',
'animation_frame'),
'area': ('x',
'color',
'pattern_shape',
'facet_col',
'facet_row',
'animation_frame'),
'scatter': ('x',
'color',
'symbol',
'facet_col',
'facet_row',
'animation_frame'),
'imshow': ('y', 'x', 'facet_col', 'animation_frame'),
'box': ('x', 'color', 'facet_col', 'facet_row', 'animation_frame')}}
Next Steps¶
- Explore different Plot Types
- Learn Advanced Usage patterns
- Check the API Reference